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In your previous module, you tackled the difficult task of learning how to 
debug a computer program. The module showed you how some of the most common 
types of errors work their way into your programs and how you can quickly 
locate these errors and correct them. 


In this module, we will review and work with program documentation. 
Program documentation is a very important part of programming, but is often 
neglected because of a lack of understanding of its true value. 


New programmers generally see no purpose in writing manuals on how a 
program works, especially after a program is up and running. They fail to 
realize that a program may need to be modified at a later date or that another 
person may be required to work on the program. Without good documentation, 
future upgrades or modifications cannot always be made quickly and accurately. 


If there is no documentation available, a program upgrade or modification 
might as well be a new program ... it will take just as long to accomplish. 
Thus documenting your program work early can save lots of time, trouble and 
effort later on. 


Documentation comes in three parts: 

* the user manual which tells how to use the program 
* comments in the source code 

* a technical reference manual 


The second and third items are only for the programmer, the first is 
generally used by everyone. 


Good user documentation is also important for any commercial program. No 
one wants to pay good money for a poorly documented (or undocumented) program, 
and no one, having bought such a program, will recommend it to anyone else. On 
the other hand, a good program with good user documentation will practically 
sell itself. 


Module 7 discusses all three types of documentation, and describes when to 
write each, as well as what belongs in each. It also gives examples and ideas 
for proper documentation of programs. 


In your next module, MODIFYING AND UPDATING PROGRAMS, we will see how good 
documentation will help reduce the time it takes to modify a program. Program 
modification should only take a fraction of the time it takes to write a new 
program if good documentation exists. 


This module will also show you how to use documentation to develop the 
procedures necessary to accomplish program change with minimum distress. 


Sincerely yours, 
x 
Kenneth J. Bigelow 


Project Engineer 
McGraw-Hill CEC 
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Overview for the Commodore 64 and 128 Computers 


CONTEMPORARY 
PROGRAMMING 
AND SOFTWARE 
DESIGN SERIES 


Welcome to Module 7 in the Contemporary 
Programming and Software Design Series. In this 
module, we turn from actual program development 
to one of the most neglected and yet highly 
important phases of the programming process: the 
requirement of documenting the program. 

Documentation is very often left until last be- 
cause it contributes nothing to the program itself. 
Furthermore, if the documentation is written too 
soon, it will have to be modified as the program is 
corrected. Accordingly, documentation is post- 
poned until all changes and corrections have been 
made to the program. 

Unfortunately, tight schedules and sometimes 
laziness often mean that the documentation, al- 
ready delayed by more urgent considerations, is 
completely forgotten in the rush to move on to the 
next (high priority) program. The completed and 
debugged program is made available for use as is, 
and stands alone on the computer system. 

People trying to use the program (except for the 
original programmer) now must figure out how to 
use the program on a trial-and-error basis. Other 
programmers have no opportunity to either test or 
contribute to this program. And in 6 or 12 months, 
when the program must be updated or extended, 
even the original programmer cannot recall all of the 
clever routines and techniques that he or she 
incorporated into the program. As a result, this 
program must be replaced with an updated pro- 
gram, rather than updated itself. 
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To avoid these and some other problems, the 
programmer must maintain appropriate documen- 
tation, both during the development of the program 
and after the program itself is complete. Most of the 
documentation is properly performed after the 
program itself is.complete. However, certain key 
documents must be started and maintained during 
the program development process. 

In this module, we will examine the different kinds 
of documentation required with programs, and we 
will explore the uses and needs for each kind. 

As with all of your program disks, the enclosed 
disk is formatted single sided, for the Commodore 
64 computer. It will also run on the C128, in 64 
mode. 

Before you begin using your program disk, we 
suggest that you place a write-protect tab over the 
notch in the side, and use the BACKUP program 
from Module 1 to make a backup of this disk. Then 
use your backup copy throughout the module. 

If you need to make additional backups of your 
program disk for your own use, by all means do so. 
However, please keep in mind that all of the 
enclosed programs and text files are copyrighted. It 
is illegal to give or sell copies of this disk or any 
programs on it to anyone else. 

To begin your study of documentation, turn on 
your peripheral devices and your computer, place 
your program disk in Drive 8, and type in the 
commands: 


LOAD “WELCOME”, 8<return> 
RUN<return> 


When the computer tells you to do so, open your 
Learning Guide to the introduction. Your study of 
program documentation starts now. 
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CREATING MEANINGFUL 


DOCUMENTATION 


If you have not already done so, turn on your 
computer, place your Program Disk in Drive 8, and 
type in the commands: 


LOAD “WELCOME?” 8<return> 
RUN<return> 


Return to this point when your computer instructs 
you to do so. 

Whenever you buy a new tool or appliance, one 
or more “Owner's Manuals” or “User’s Manuals” are 
packed with it. If you do not already know all about 
the tool or appliance, you can refer to this manual 
for information you will need to install and use your 
new purchase. This will include special safety infor- 
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mation and appropriate precautions as well as the 
correct operating procedures. 

Even if you are familiar with the uses of the item 
you purchased, you should still read the manual to 
see if there are any special features available that 
you might not know about. 

This is also true for programs you might buy. 
They also come with an Owner’s or User's Manual. 
In this case, the manual tells you what the program 
is intended to do, what kind of computer is required 
to run it, and what hardware must be available for 
correct program operation. For example, a commu- 
nications program might require a serial commu- 
nications interface and modem, which would be 
considered optional equipment for the computer, 
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rather than inherently built-in hardware. Other pro- 
grams (especially games) might require the use of a 
color monitor and graphics display adapter. Some 
programs require a certain minimum amount of 
memory (RAM), while others cannot work well un- 
less a hard disk drive is available. 

Other information in the manual includes the in- 
structions that will be recognized by the program 
and the necessary syntax for using each of them. 
Procedures for backing up the disk (if it is not copy 
protected) or for obtaining backups might be in- 
cluded, as well as any requirements for setting up 
the computer and initializing the program. 

Many programs require a configuration procedure 
before they may be used for the first time. This lets 
the user define the precise printer available, which 
printer and/or serial I/O port to use, and other fac- 
tors which will vary from one system to another. The 
User’s Manual will include the exact procedure for 
performing this initial configuration, as well as the 
method of reconfiguring the program if the hard- 
ware should be changed later. 

All of this information is only part of the docu- 
mentation that belongs with any program. This is 
the user’s information, which is supplied to the user 
along with the program. This documentation should 
provide the user with all information required to 
operate the program in its intended manner. In most 
commercially provided software, this is the only 
documentation actually provided with the program. 

The company or individual who provided the 
program to the user requires more documentation 
than this. First, the program source code must re- 
main on file, so that it can be examined and updated 


at a later time. Second, there should be a program- 
mer’s manual describing the internal workings of the 
program, so that any programmer can examine and 
update the program at a later time, without having 
to figure out what the program is doing first. 

The User's Manual must always be made avail- 
able in some form. The rest of the documentation is 
too often neglected, however, leading to future 
problems. 

In this module, we will examine each type of 
documentation, see how it is used and why it is 
needed, and see how it can be produced without 
requiring excessive amounts of time and effort. 
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WHAT IS DOCUMENTATION? 


Before we can discuss documentation intelligently, 
we must first have a clear idea of exactly what it is we 
are talking about. Good documentation is important 
for full use of a program, while bad documentation 
can be worse than none at all. 

If your computer is available at this time, LOAD 
and RUN the program “TRACK1” from your 
Program Disk. Return to this point when your 
computer instructs you to do so. 

All documentation is intended to be read by peo- 
ple who must either use or work with the program. It 
does not have anything to do with the operation of 
the program itself, and is not used by the computer. 
Nevertheless, documentation is a very important 
phase of the programming process. 


Sector 1: The Need for Documentation 


Consider a program on disk for the IBM PC, with 
the name FM.EXE. What does this program do? 
Even the program name doesn’t help much. If 
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anything, the program name suggests that this 
might be a program dealing with the FM radio 
broadcast band. 

Actually, this is a Finance Manager program 
which is available from many sources as User-Sup- 
ported Software (or Freeware or Shareware, as it is 
sometimes called). It is supplied in a program “li- 
brary” called FM.LBR, which contains not only the 
main program but also a configuration file, docu- 
mentation file, and two complete working examples 
which are described in the documentation file. 

Another Shareware program is IPM.COM. Again, 
the program name is not very helpful in describing 
its functions. If you had only the program, you 
would have a lot of trouble using it. Fortunately, the 
program itself has some built-in help, but this in itself 
is a form of documentation. This program is a pro- 
ject scheduler using the critical path method. As with 
the FM program, IPM is distributed with a .DOC file 
that can be printed out to describe the operation 


and uses of the program. 
Some programs are designed to help the user 


with explanations, menus of valid commands, etc. 
However, this is not always the case. Suppose, for 
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example, that you had to use NRIBUG with no 
information whatsoever about the available com- 
mands or their syntax structures. When you type in 
NRIBUG<return> the computer responds with a 
register display and the character “.”, and waits for 
acommand. If you don’t know the valid commands, 
you can get a lot of “?” messages before you 
determine which commands are acceptable and 
which are not. Even then, you will have to experi- 
ment further and endure many more error mes- 
sages in order to determine the meaning of each 
command and any data that goes with it. If the 
commands were two-letter or three-letter com- 
mands, this task would become nearly impossible. 
Clearly, a program like NRIBUG requires some 
accompanying information before it can be used on 
a practical basis. This accompanying information is 
the user documentation, which will tell the user 
about each command and how it is used. 

In the same vein, suppose you, as a programmer, 
wish to add a new instruction to NRIBUG, or 
possibly modify the operation of an existing in- 
struction within NRIBUG. How would you go about 
it? Could you even find out where in the program 
each instruction is carried out? How would you find 
the “idle loop,” where NRIBUG awaits the next user 
command? 

There are ways of finding such things in a pro- 
gram, and we will explore them in our next module. 
It would still be easier and more certain if we had a 
document describing the internal workings of the 
program and correlating program functions with a 
source code listing of the program itself. It would 
also be helpful if the source code listing had com- 


ments that would help to correlate different parts of 
the program with their intended functions. This kind 
of information would allow you to follow the original 
programmer's logic when writing the original pro- 
gram, and to easily locate the part of the program 
you wish to adjust. 

Now suppose you have in front of you a com- 
puter program that has been modified several times, 
and is to be modified yet again. Each modification 
corrected a small bug or else added a new capability 
to the program. Your task will be to locate and 
correct a minor bug that appeared following the last 
extension to the program. The programmers who 
previously worked on the program are not available; 
they are now working for other companies and can- 
not be reached in any way. 

As you look through the paperwork you have on 
hand, you find the original user’s manual for the 
original version of the program and a few scraps of 
paper listing the added commands. You have noth- 
ing, however, to indicate the recent history of the 
program, so you do not know how or when any 
modifications were made to the program. Even the 
source code listing is very different from the present 
source code. How can you expect to make addi- 
tional changes to the program? 
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Sector 2: Different Kinds of Documentation 


With many different kinds of information required 
about a program, and with only certain information 
required by any one person, we find it convenient to 
divide documentation into several different catego- 
ries according to how it will be used. For the same 
reason, each document is provided only to the peo- 
ple who will need it. Documentation is classified as 
follows, according to its purpose. 

The User’s Manual. This manual is intended 
primarily for people who will use the program on 
their computers, without having to know how the 
program itself works internally. See Figure 1-1. It 
should be written so that a nonprogrammer can 
nevertheless get the program to perform all of its 
intended functions and operations. 

This document contains a list of each command 
that may be given to the program along with a 


DIFFERENT KINDS OF DOCUMENTATION 


1. The User’s Manual: 
* goes to each user of the progran. 
* explains what the program does. 
‘ explains how to use the progras. 
: defines each command and its operation, 


Figure 1-1. The contents of the User's Manual. 
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DIFFERENT KINDS OF DOCUMENTATION 
1. The User’s Manual: 


2. The Source Code: 
: is for the programmer(s). 
: briefly describes the purpose of the program. 
» includes a short history of program updates. 


: includes coments that guide the programmer 
through the listing. 


Figure 1-2. The preferred additions to the program source 
code. 


detailed description of the command and its syntax. 
It should also contain examples of proper usage of 
the command. 

If the program produces various informative dis- 
plays or menus, each such display should be de- 
scribed and all command options at that point listed 
and described. Such displays during the normal 
operation of the program are quite helpful, and area 
worthwhile part of user documentation. The User's 
Manual should be made available to anyone who 
has anything whatsoever to do with the program. 

The Program Source Code. This is the code 
actually written by the programmer, modified and 
updated since it was originally made available. It 
should include comments throughout, describing 
the purpose of each functional block of program 
code. Comments should also be used to identify all 
modifications made to the original program code, in 
order to update the program periodically. This is 
shown in Figure 1-2. 
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The program source code should begin with a 
series of comments which identify the program and 
its general purpose. This does not include details, 
which will go into other documents. Nevertheless, 
the first several lines should contain the program 
name and its functional purpose. They should also 
contain the date on which the program was finally 
debugged and made available for use. 

Each time a modification is made to the program, 
the date and nature of the modification should be 
placed above any other comments at the beginning 
of the program. Thus, the front end of any program 
source listing should be a complete statement of the 
origination and modification history of the program. 

The Technical Reference Manual. This docu- 
ment contains all of the details of program develop- 
ment for the particular program. It may or may not 
include a source code listing, but should include the 
update history of the program. Refer to Figure 1-3. 

The technical reference manual or document 
should also identify any mathematical algorithms 
used to perform calculations, simulations, etc. Stan- 


Figure 1-3. What goes into the Technical Reference Manual. 


dard equations can simply be identified, but spe- 
cialized equations should be listed and their method 
of implementation stated. Thus, the calculation of 
square roots might be stated as being performed 
using the Newton-Raphson algorithm. 


Note: For those who are curious, the Newton- 
Raphson algorithm is a method of successive ap- 
proximation for calculating the value of a function 
for a given value of the unknown. It requires that 
you be able to determine the first derivative of the 
function. The general form of the algorithm is: 


_y — 4X) 

Se 
If you start with a guess, X, of the correct answer, 
this expression will return a better guess as Xp. Using 
the better guess as a new guess will give an even 
better guess. This procedure rapidly converges to 

the correct answer. 

To find the square root of a number, N, the func- 
tion, {(X) = X2 — N = 0. The first derivative of this 
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function, f'(X) = 2X = 0. Thus, the general ex- 
pression above can be rewritten as: 


WN 
Xp = X - OX 


This expression can be further reduced algebraically 
to: 
=a WN 
Xo = 2X 
This particular technique is fast and easy to imple- 
ment for calculating square roots, so it is often used 


for this purpose. It is also quite useful for calculating 
other functions as well. 


The technical manual does not have to contain 
flow charts or the original program design criteria, 
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although these might be included if they are helpful 
to a full understanding of the program’s operation. It 
should contain any and all information that may be 
either required or helpful for another programmer to 
completely understand the program’s internal work- 
ings. 

The combined documentation for a program 
should clear up any questions or mysteries about 
the program. If you have discovered or invented a 
clever way of performing a task, describe your tech- 
nique in detail. The idea is to make the information 
available to other programmers or even to yourself 
sometime in the future. Don’t try to hide your ideas 
here; this document will not be made available to 
anyone who should not have it. If you:don’t docu- 
ment your ideas, you will only be hiding them from 
yourself, which makes no sense at all. 

Now that we have an idea of what documentation 
is, why we need it, and what kinds of documentation 
we will need for our programs, let’s take a detailed 
look at each kind of documentation and see when 
and how it should be generated. 
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NOTES: 


8 MODULE 7 


TRACK 2 


THE USER’S MANUAL 


The User's Manual is the document written by the 
programmer to tell even nonprogrammers how to 
use a particular program. This is quite possibly the 
only document the end user will see, so it is very 
important that this document be complete and easy 
to use. 

If your computer is available at this time, LOAD 
and RUN the program “TRACK2” on your Pro- 
gram Disk. Return to this point when your com- 
puter instructs you to do so. 

The User’s Manual is normally divided into sev- 
eral sections, as shown in Figure 2-1. It starts with an 
introductory section to give an overview of the pro- 
gram and its operation. It then describes, in full 
detail, each command recognized by the program. 
In many cases, a tutorial section is included to pro- 
vide a working example of a practical session with 
the program. If appropriate, a reference card or a 
short reference sheet should be included, as a re- 
minder of the instruction set. Finally, an alpha- 
betized index is needed to facilitate the inevitable 
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searches for detailed information on particular func- 
tions or commands. 


Sector 1: The Program Overview 


The first thing you want to tell the prospective user 
of your program is the purpose and basic operation 
of that program. Identify the main features and any 
major limitations of the program. Keep in mind that 
the prospective user will probably read at least the 
overview and will probably review the command set 
before attempting to use the program. The informa- 
tion presented in the overview will most likely deter- 
mine whether or not that prospective user will even 
bother to try out the program! Therefore, the over- 
view is highly important and must be written care- 
fully. 

The overview should be short (not over one page) 
and concise. The very first paragraph should specify 
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THE USER’ S MANUAL 


+ Must tell the user what the program does. 

: Must tell the user if special hardware is required. 

: Must describe the operation of each command. 
+ Must define the syntax of each command. 

+ Must state the limitations of the program. 

+ Should have a command quick-reference list. 


+ Should be comprehensively indexed. 


» Should include a tutorial or sample session. 
: Is the document that will or will not sell your program. 


Figure 2-1. What goes into the User's Manual. 


what the program is and, if appropriate, how it was 
designed to work. Typical first paragraphs might be: 


[Program name] is a database management 
system designed according to the relational 
model. It will handle up to XX open files at one 
time. 


[Program name] is a C compiler that recog- 
nizes a subset of the complete C language. It 
compiles C source code to assembly-language 
source code. The resulting assembly-language 
code may be directly assembled or it may be 
edited as desired before assembly. 


[Program name] is a complete FORTH inter- 
preter which implements the full FORTH-83 
standard. It includes a full-screen editor, com- 
plete assembler, and floating-point arithmetic 
implemented in software. 
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Each of the above paragraphs defines quickly and 
clearly the nature of the program in question. By 
looking at that one paragraph, you can immediately 
determine whether or not you want to look further 
into the program. For example, if you were looking 
for a FORTH interpreter/compiler, you would ignore 
the first two immediately and go directly to the third 
program. Further reading would enable you to de- 
termine whether or not you would be interested in 
buying or using the program. 

On the other hand, if you were interested in the C 
language, you could concentrate on the second pro- 
gram described above, and read it over to determine 
whether or not the indicated “subset of C” was 
sufficiently complete to meet your needs. 

The remainder of the overview should identify 
any special features of the program, as well as any 
limitations and any other programs that are re- 
quired. Specific details are not required at this point, 
and should not be included. These will come later. 
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In general, the overview should contain the fol- 
lowing information: 


e@ The name of your program. 

e The nature of the program (interpreter, compiler, 
spreadsheet, database manager, word processor, 
etc.) 

e The language the program implements, if any. 

e Any standard or model on which the program is 
based. 

e Any standard features that have not been imple- 
mented in this particular program. 

e Any extra features, beyond the standard, that 
have been implemented in this program. 

e Any restrictions or permissions regarding the use, 
copying, or distribution of the program. This in- 
cludes a statement of whether or not the program 
is copy-protected, the copyright notice, and any 
license restrictions that apply to the buyer/user. 


This is the information you should look for when- 
ever you plan to buy a program to determine 
whether or not the program is suited to your own 
requirements. By the same token, this is the infor- 
mation you should provide with your program, so 
that any prospective users can quickly determine 
whether or not this program is suited to their needs. 


Sector 2: The Detailed Command 
Description 


Figure 2-2 shows a definition of terms, or glos- 
sary, for use with a description of NRIBUG com- 
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mands and operations. Figures 2-3 and 2-4 show 
individual command descriptions for the A and B 
commands, respectively, supported by NRIBUG. 
This is the sort of detailed command description you 
would expect as part of the main manual. The quick 
reference card, on the other hand, would only have 
entries such as: 


A address 
B_ address 


Assemble from address 
Place breakpoint at address 


Each command available within the program 
should be described in complete detail, with all per- 
missible versions of the command syntax clearly 
indicated. If there are different levels of commands, 
so that one command may be followed by any of 
several subcommands, all of the main commands 
should be described first, followed by the subcom- 
mands. The subcommands under a single main 
command should be grouped together, so that the 
set of commands and subcommands can be easily 
referenced by the user. 


| = 
it 
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The following terms will be used to describe the operation of the various NRIBUG commands: 


Contiguous Sequentially adjacent. A single NRIBUG command cannot skip over parts of 
memory; but will deal with memory bytes in sequence. Any single block of 
memory specified to NRIBUG must be contiguous. 


Page A contiguous block of memory containing 256 bytes, all of whose addresses start 
i with the same two hex digits. The most important two pages in the 6502 
microprocessor are the Zero Page ($00xx), which permits indirect indexed 

addressing, and Page 1 ($01xx), which contains the stack. 


eee Any of the 8-bit memory words contained within the CPU. The registers of most 
interest to the programmer are the accumulator (A) and the index registers (X 
and Y). Two other registers that can be accessed by the programmer are the 
stack pointer (SP) and the program counter (PC). The PC is the only register in 
the 6502 that contains 16 bits; all others contain only 8 bits. 


The complete address of a single byte in memory, specified as a 16-bit or 
4-hex-digit number. 


A block of contiguous memory described by the first and last addresses that 
make up that block. 


Square brackets are used to indicate that a parameter following a command is 
optional. 


mber A number is a hexadecimal number up to four digits in length used directly as a 
command parameter. 


A series of bytes or words specified as parameters for a NRIBUG command. 


Figure 2-2. Definitions of terms used to specify the operation Of NRIBUG COMMANGS. eee 
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COMMAND: & Assemble code to memory 


FORMAT: A address 


Accepts assembly language source code, one line at a time, 
| and assembles it to memory starting at address. If an 

error is detected, it will be flagged and that input line 

ignored. If the entry is accepted, a new A command will 

be issued, followed by the next available address in 

memory, awaiting the next mnemonic. Pressing <return>? by 

itself will terminate the assembly process. 


TYPICAL USAGE: 


A 3000 ¢return> Begin assembly at address 2000 


Figure 2-3. A description of the A command in NRIBUG, as it might appear in a User's M@mUuall. cece 


COMMAND: B Set or remove a breakpoint in a program 
FORMAT: B Cedd@ress] 


Where address is the location of the breakpoint to be set 
in the program. If address is omitted, the last break— 
point set will be removed. 


A breakpoint is set by replacing the op code at address 
with a BRE instruction. This causes control to return to 
‘ NRIBUG when the BRE instruction is executed. 


Any mumber of breakpoints may be set in a program at any 
time. However, NRIBUG remembers only the Jeast breakpoint 
set; any previously set breakpoints cannot be restored 
with the B command. - 


TYFICAL USAGE: 
B 2020<return> Set a breakpoint at location F020. 


Save the op code at that location 
for restoration at 3 later time. 


Béreturn> Restore the original op code to 
the memory location where the last 
breakpoint was set. 


Figure 2-4. Describing NRIBUG’s B command. 
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A very useful way of organizing a program is to 
include menus. These are screen displays which act 
as quick reference charts for those commands which 
are available at any point in the program. Often, 
more detailed descriptions of commands are also 
available as additional help, directly from the pro- 
gram. These are useful, especially to a new user of 
the program, but do not take the place of the printed 
manual, which should still be complete. We will take 
a closer look at menus and similar techniques in the 
next track. 

The detailed command description should in- 
clude a clear definition of any terms that are either 
not commonly used in normal conversation or 
writing, or that have a special meaning within the 
context of the program. Thus, in Figure 2-2 we 
carefully defined our terms to avoid confusion as 
much as possible. It is not necessary to redefine the 
terms for each command, but the typical syntax 
descriptions should include enough variations to 
clearly indicate what sorts of command structures 
are permitted. 


Sector 3: The Program Tutorial 


In most cases, defining the commands available to a 
program is not sufficient to explain how to use that 
program to the best possible advantage. To provide 
information on operating procedures and useful 
techniques, you should include one or more brief 
“sample sessions” in the User’s Manual. These sam- 
ple sessions form a user’s tutorial. 
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The tutorial should normally be broken up into 
several “bite-sized” sessions. The first lesson should 
define the minimum requirements (both hardware 
and software) for running the program, and show 
how to get the program started. The second lesson 
should then show how the user can actually use the 
program in its simplest operating mode. The third 
lesson then would cover how to save the work done 
and exit the program. 

Additional lessons can cover the various extra 
features and special capabilities. There should be at 
least one lesson dealing with each capability of the 
program, so that the user can see a real and practical 
application for each feature. Typical screen displays, 
including any and all menus, should be shown ex- 
actly as they will appear to the user. Also, the user 
should be able to follow the instructions exactly, and 
obtain the same results as those described in the 
manual. 

The purpose of the tutorial section is to provide 
the user with some experience in using the program, 
so that he or she can proceed to use the program for 
other applications with some degree of familiarity. It 
is very difficult to learn how to use a program cor- 
rectly and effectively while trying to actually apply 
that program. The predefined tutorial provides the 
needed experience before the program is actually 
put into working service. 


MODULE 7 


Creating Meaningful Documentation 


The existence and use of a tutorial section is more 
important than you might expect. Many times a 
manager or supervisor will decide that there is not 
enough time to spend four to eight hours going 
through a tutorial, only to repeatedly ask for help in 
using a new program. This sort of piecemeal as- 
sistance can cost several man-days on the part of 
both the manager and the experienced user. 

Tutorials are sometimes provided as demonstra- 
tion programs on disk, rather than as printed 
lessons. This sort of approach is more complicated 
for the programmer, but has the advantage that the 
user can go through a wide range of “what happens 
if... ” experiments without risking any important 
data. 
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Sector 4: The Index 


Once you begin to use a program, you will quickly 
memorize the main commands that you deal with 
on a day-to-day basis. Then you will find that you 
no longer need or want all of the menus to be on 
screen at all times. You won’t always be using all of 
the commands available to you. Some commands 
and functions are seldom used but are very handy 
on the few occasions when they are needed. 

The problem is that such commands are not easily 
memorized, and you are likely to forget exactly how 
to use them. You may even forget the exact com- 
mand to perform a given function. You don’t want 
to have to go through the entire User’s Manual to try 
to locate the particular command you want or the 
tutorial section dealing with that command. You will 
want a fast method of finding the command descrip- 
tion you need. 

This is the purpose of the index. Most technically 
oriented books contain an index at the back. This 
index is an alphabetized listing of the key words, 
names, and concepts covered in the book. Unlike 
the table of contents, the index does not list topics in 
the order in which they appear in the book, but 
rather in alphabetical order with all page numbers 
where any reference to the concept or topic can be 
found. 

Using the index, you can locate all the informa- 
tion you may need about any command, even if 
you are not sure ahead of time of the command 
name. 

Just as you want to be able to use the index in a 
book to quickly find the specific information you 
need, you should be sure to make your index com- 
plete and detailed. Remember that you are writing 
the User’s Manual for someone who has never seen 
your program before, and may not be all that famil- 
iar with computers and their operation. 
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Sector 5: General Considerations 


As you write the User’s Manual for your program, 
keep in mind that the user cannot read your mind or 
determine what you meant as opposed to what you 
actually wrote. Therefore, make sure that what you 
write is really what you meant to write. 

Do not try to make the user’s manual too short. 
The entire manual should be clear and complete. 
Remember that the user will be unable to come to 
you with any questions or problems, so do your best 
to answer them ahead of time. One of the most 
frustrating experiences for any user is to buy a new 
program, open the package, and find that the docu- 
mentation consists of the paragraph: 


Insert the enclosed disk into the drive and 
type GO. Then press the RETURN key. Your 
command options will appear on the screen. 
We hope you enjoy our program! 


Of course, this is an extreme example, but scanty 
documentation can be just about this frustrating. 
Most users, upon seeing such limited instructions 
and documentation, will refuse to buy the program 
in the first place. If they have already bought it, they 
will tell their friends about this problem, and they 
won’t buy it. Any reviews of your program will have 
negative comments on the documentation, which 
also won’t help. 

While it is important that your User's Manual be 
complete, it should also be concise. Long, wordy 
manuals are hard to use, because it is difficult to 
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locate the desired information and isolate it from all 
the verbiage. 

This mistake is easy to make, especially for new 
programmers who are trying to make sure the docu- 
mentation is complete. Long documents are some- 
times found with User Supported software as well. 
In this case, the User’s Manual is provided as a text 
file on the disk and was produced using a word 
processing program. The final formatted manual is 
then printed out to a disk file, rather than to paper. 
As a result, the author may not realize ahead of time 
just how big the manual has become. Some man- 
uals are well over 100 pages long and occupy more 
than half of the available space on the distribution 
disk. In some cases, the manual is recorded on the 
disk in “squeezed” form to take up less space. The 
user must then unsqueeze the manual in order to be 
able to print it out. 

Making the User’s Manual complete and long 
enough without making it too long does take some 
practice. The best way to check your own work is to 
print it out, and then see how easily you can locate 
various key concepts throughout the manual. If you 
can’t find it at all, your manual is too short. If the 
concept is spread out over six paragraphs, the man- 
ual is too long. 

One more important factor is spelling. A correctly 
spelled manual looks good and has a positive ap- 
pearance. A lot of spelling errors will give a manual 
an amateurish appearance and will tend to suggest 
that there might be as many errors in the program as 
there are in the manual. 

A good User’s Manual will provide an enhanced 
user image of the program, just as a poor one will 
detract from the value of the program. Therefore, 
use as much care in the writing of the User’s Manual 
as you do in the design and writing of the program 
itself. This care will prove to be worthwhile in the 
long run. 
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USER ASSISTANCE FROM WITHIN 


THE PROGRAM 


The User’s Manual is essential, and must be in- 
cluded with any commercially sold program. You 
should write at least a short User’s Manual even if 
the program is exclusively for your own use. Other- 
wise, you may have trouble remembering all of the 
instructions the next time you go to use it. 

It is sometimes inconvenient, however, to go 
searching through a book or even a quick reference 
card while you are using a program. For this reason, 
many programs include menus that help to guide 
the user through the operation of the program. If 
properly done, this approach can help to make the 
program more “user-friendly.” 

There are several techniques that can be used to 
provide help while a program is operating, and each 
one has its advantages and disadvantages. Also, 
each method is most useful with certain types of 
programs. Let’s take a close look at each of these 
methods. 


Sector 1: The Fixed Menu 


The first method that was implemented in working 
programs (and the simplest to accomplish) was the 
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fixed menu. In such a program, any time the user 
has a choice of commands, the main display is 
replaced by a list of available commands, along with 
their meanings. Once the user has made a choice, 
the command menu disappears, and is replaced by 
the next display. This may be either a secondary 
command menu or the appropriate working display. 

This method is still very popular for providing the 
initial selection menu when a program is first started. 
A number of different word processor programs, 
such as MicroPro’s Wordstar™ and Easywriter™ 
from IUS both start with an initial file-handling 
menu and include a directory display of the cur- 
rently logged data disk. Both your command op- 
tions and the currently available files are displayed. 
Once you have selected a file to edit or print, you 
can either load it in or proceed to work with it as 
necessary. 

This approach is highly advantageous, especially 
for new users of a program. As you become more 
familiar with a program, you no longer require such 
detailed menus. An initial menu still does no harm. 

On the other hand, while new users of a program 
often like to see menus to remind them of current 
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command options, such menus take up screen 
space and tend to slow down the operation of the 
program. Therefore, experienced users object to 
the excessive use of menus, since they can operate 
the program without them. 


Sector 2: The Pop-Up Menu 


The answer to this problem is to make the menu 
available without requiring its appearance all the 
time. Thus, the user can either have the menu pre- 
sent or not, according to experience and the require- 
ments of the moment. This can be done in several 
ways. 

For example, Wordstar™ allows the user to set 
“Help Levels.” The choice of help level determines 
which menus and submenus will be displayed, and 
how much information will be included in the menu 
displays. As you become more proficient with Word- 
star, you can gradually reduce the help level, so that 
you will have more room for the text display. 

Easywriter I™ uses one of the function keys to 
display the edit command menu on the top half of 
the screen. Pressing the same function key again 
removes the menu and allows the entire screen to 
be used for text. 

The advantage of this kind of approach is that the 
menus only appear when the user wants them, 
rather than all the time. They are still fixed menus, in 
that they display predefined information in a pre- 
determined manner, and the user cannot select what 
information is to be displayed unless a submenu has 
been predefined by the programmer. 
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Sector 3: The Help File 


A “help file” is a separate text file on disk, which can 
be called by the program in use. In its simplest form, 
it simply contains a list of available commands which 
the program can use. When the user asks for 
help, the program opens the help file, displays the 
text on the screen, and waits. When the user presses 
a key, the display reverts to the previous screen 
contents and the file is closed. If the command list 
fills more than one screen, each screen is displayed 
in turn, until the command set is exhausted. 

The problem with this approach, of course, is that 
it is effectively the same as the fixed menu. It has the 
advantage that it is not a required part of the main 
program, and can be left off the disk if it is not 
required. But it still displays a full set of command 
options with little detail, just like a quick reference 
sheet. 

A more effective technique with help files is to 
provide a detailed description of each command, 
and to use selected control characters within the file 
to identify each command individually. Using this 
technique, if you just ask for help, the program will 
simply list the commands, as with the fixed menu. 
You can then take it a step further by asking for help 
with a specific command. The program would then 
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search through the help file for the specific com- 
mand, and display detailed information on that 
command alone. 

The information displayed this way can be as 
detailed as that provided in the User’s Manual, but 
available directly on the computer. If the command 
description is not in the help file, a “command help 
not found” message is issued, followed by the list of 
commands for which help is available. 

The advantage of this approach is that you need 
not “hunt” for a particular command in a list; the 
computer does that for you. In addition, the descrip- 
tion and explanation of each command can be given 
in much more detail than would otherwise be possi- 
ble. Another advantage is that once you have 
learned the commands, you can delete the help file 
and free up that disk space for data, if desired. This 
is not possible for programs with built-in menus. 

Menus and help files can act as very useful exten- 
sions of the User's Manual; however, they do not 
replace the User’s Manual. They should be provided 
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(if appropriate) in addition to it. The user’s primary 
source of information about the program should still 
be the printed manual. 

In some cases (especially User Supported Soft- 
ware), the User’s Manual is provided in the form of 
one or more text files on disk, rather than as a 
printed manual. This saves printing and mailing 
costs, and is acceptable because the program itself is 
provided free of charge. 

This approach is not acceptable with commercial 
software. If you charge for your program (other than 
voluntary user contributions), you should supply a 
printed User’s Manual. Menus and help files for use 
by the program during operation are nice, but do 
not stand alone. 
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TRACK 4 


DOCUMENTING THE PROGRAM 


SOURCE CODE 


The program source code is what you have spent a 
substantial amount of time to design, develop, and 
debug. When it is done, it will be in a form that a 
compiler or assembler program can read and con- 
vert into absolute machine code. 

Unfortunately, while you can read and under- 
stand each instruction in the source program, you 
cannot always read from those instructions the pur- 
pose of a group of instructions. This is especially true 
when you have found or designed a more efficient 
method of accomplishing a task, which does not 
appear logical or rational at first. Clearly, some ex- 
planation is called for, so that you or another pro- 
grammer can follow the logic of the program at 
some later date. 

Part of that explanation should already be present 
in your program as brief comments to define the 
main purpose of each segment of the program. This 
constitutes only a fraction of the complete docu- 
mentation of the source code. 

If your computer is available at this time, LOAD 
and RUN the program “TRACK4” on your Pro- 
gram Disk. Return to this point when your com- 
puter instructs you to do so. 
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In many cases, once the User’s Manual is com- 
plete, the programmer files the program away as 
finished, and then goes on to another project. If this 
is a program being developed by a company pro- 
grammer for internal use within that company, the 
programmer's supervisor will often pressure the pro- 
grammer to ignore the documentation, simply be- 
cause it takes time. Management would prefer to 
have that time spent on the next program, rather 
than on the one already considered complete. This 
creates a problem when corrections or updates are 
to be made to the program, because the existence of 
documentation would make the work go much 
faster and easier than would otherwise be the case. 
In extreme cases where no documentation exists, 
the original program may have to be discarded al- 
together, and a new one written. This takes far more 
time than the proper documentation of the original 
program would have required. 

With these thoughts in mind, let’s consider just 
what should be included in the program source 
code for proper documentation. 


21 


Creating Meaningful Documentation 


Sector 1: The Purpose of the Program 


At the very top of your source code, you should put 
in a few comment lines that tell the name and basic 
purpose of the program. This will allow you or an- 
other programmer to quickly match up the printed 
source listing with the other documentation. 

Along with the program name and current version 
number, you should include a brief description of 
what the program is intended to accomplish. Do not 
go into details here. The maximum description 
should be about two paragraphs in length. Save the 
details for the Technical Reference Manual. 

The idea here is to put enough identification at 
the beginning of the source listing so that you or 
another programmer will have no trouble telling 
what the program is all about, and which other 
documentation to look for to help understand the 
program, if necessary. 
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Sector 2: The History of the Program 


The next several lines of source code should de- 
scribe the history of changes and updates performed 
on the program. This includes the date of the modi- 
fied program and the version number assigned to it, 
as well as a brief description of the change. The 
latest change should be listed first. 

When a program is first released for general use, it 
should have a history stating only the following, or 
something similar: 09-06-85 Initial release of the 
program. V. 1.0.0 

No description of the program is necessary. This is 
covered in the “purpose” section which precedes 
the history description. 

The next history entry should precede the original 
entry, so that the latest entry will come first in the list. 
Thus, the first-round adjustments to this program 
would be accompanied by another history entry just 
above the initial entry. The resulting complete his- 
tory section would look like this: 


10-15-85 Fixed bugs in display routine. 
V. 1.1.0 Added lower-case capability to input. 


09-06-85 Initial release of the program. 
V. 1.0.0 


Further modifications are described in a similar 
fashion, with each adjustment being described at the 
top of the existing list. As a result, you or any other 
programmer can quickly review the history of the 
program throughout its use. 

In the version number, successive digits represent 
decreasing levels of importance of changes. Thus, 
version 1.0.1 of a program would indicate only a 
slight change from version 1.0.0. Most likely, only a 
slight bug will have been corrected. In the example 
just shown, adding lower-case handling capability to 
the program constitutes a larger adjustment than 


MODULE 7 


Creating Meaningful Documentation 


this, so the version number was changed to 1.1.0 
rather than to 1.0.1. 

In some cases, the second decimal point is left 
out. If this is the case in a program you are working 
on, keep in mind that the digit positions are still in 
order of decreasing significance, and that only indi- 
vidual digits have significance. Thus, version 1.2 of a 
program is newer than version 1.11. If the third digit 
is omitted, it is assumed to be 0. 

The use of this pattern of version numbers makes 
it very easy to scan the history of a program. By 
looking at version numbers and dates, you can 
rapidly determine when the last change was made 
and how major it was. You can also determine how 
many bugs had to be fixed within each past version 
and how long it took to find and fix them. This 
information is a clear indication of the quality of the 
program as well as how useful others have probably 
found it to be. 


Sector 3: Commenting the Program Itself 


As we mentioned in the modules dealing with pro- 
gram coding, you should include some explanatory 
comments as you write the program source code. 
These comments can then help you to locate vari- 
ous functional blocks within your program, to either 
modify them or to check on their precise require- 
ments. 

Once the source code has been completed and 
debugged, however, you should add some more 
comments to the program. These comments should 
identify the purpose of every constant and every 


MODULE 7 


Track 4 


routine, as well as indicating the input and output 
conditions for each routine and subroutine. 

Of course, it is not necessary to place a comment 
on every line of the program. It is desirable to in- 
clude enough explanatory comments so that you or 
any other programmer would be able to understand 
the entire program logic just from the source code 
listing. 

In order to accomplish this, each subroutine 
should be identified in terms of what it does, what 
inputs it requires, and what outputs it produces. Any 
use of registers or memory locations should be 
clearly stated. If you have already included some of 
this information during the coding process, fine. If 
anything is still unclear, clarify it now. Assume that 
you will remember nothing about the program the 
next time you see this listing; too often that assump- 
tion is accurate. 

Figure 4-1 shows a segment of assembly- 
language code for a program called “BYE.” This 
program is intended to run under CP/M, so it is 
written in 8080 assembly language. The purpose of 
the complete program is to operate the computer in 
conjunction with a modem and communications in- 
terface, so that it will accept a telephone call from a 
remote computer or terminal and establish commu- 
nications with the remote terminal just as if the user 
were sitting at the computer keyboard. The particu- 
lar code section shown in Figure 4-1 is called when 
the phone rings, answers it if the modem won’t do 
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IMRINI: 


oy 


Figure 4-1. 
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START BSIM CODE 


BSIM 
MDINST 


MD INF 
7FH 


BSIM AND FRGRSS 
RCDISF 

PSW 

H, LFMSG 

PRINTL 

PSwW 


BSIM 
CR 


Ee: 


tar 
= 


REDOIT 


ae ane oe we ae 


‘os es ue 
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JOO OOOO OG OOOO GGG OGG KK Ix 


Character ready from modem? 
No 

Get the modem response code 
Strip parity 

BSIM 


Display FC for local sysop 


Turn up a line on ert 


FPRGRSS 


Ring? 
No, something wrong, start over 
BSIM 


BSIM AND (NOT NOATA) 


B, 22 
DLF 1 
EATALL 
H, BSATA 
IMSEND 


BSIM 
B, 20000 


MDINST 
RCHEE. 
MDINF 
O7FH 


BSIM AND FRGRSS 
RCDISF 


BSIM 
CR 
MDF 1 
LF: 
MDR1 


Po 


‘nt ae ne cae 


Must let the phone quit ringing first 
Usually takes from 1.4 to 3.7 seconds 
Swallow c/r or 1f from result code 


Send ATA to modem 
BSIM AND NOT NOATA 


We will check for FRC every 1 ms for 30 secs 


And wait for response 
Then fetch it 

And strip parity 

BSIM 


And show results code (RC) 
BSIM AND FRGRSS 


8080 source code to wait for ring, answer telephone, and set modem to the callers data rate. 
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CPI werd 

Jz IMRING 
CFI aS 

JZ REDOIT 
CPI *4* 

JZ REDOIT 
CPI i 
JNZ MDR2 


=e an ue 


CALL CHECK 1 
ENDIF 
IF BSIM AND FRGRSS 
CALL RODISF 
ENDIF 
: 
if BSIM 
CPI *O? 
a2 SET24 
CPI 4? 
Vz SETZ4 
: OMF: SETS 
MDR2: CFI 7S? 
ez SET12 
CPI *&? 
JZ SET24 
ENDIF 
3 
IF BSIM AND ANCHOR 
IMF: SETS 
ENDIF 
i 
IF RS IM 
IMF MDFA1 
S 
RCHEK: CALL KDELAY 
DCX E 
mov A.C 
ORA E 
INZ MDR1 
REDOIT: POF H 
LXI H, VONUM 
INF M 
LXI H, LEMSG 
CALL PRINTL 
CALL MDSTOP 
IMF: HANGUP 1 
ENDIF 
3 
IF BSIM AND FRGRSS 
RCDISF: PUSH B 
PUSH H 


Pe ee 


ee we 


Get next character if first was 


oe 


“2 ee ae 


ues 
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Missed ring indicator? 

Answer again 

Carrier wait timeout? 

Yep, timeout (voice call maybe) 
Error? 

Start over 

200 baud or 2400 bps? 

No, check for 1200 bps 


ie 
Let’s see if it’s al, 10 or it 


BSIM 


Show RC to local terminal 
BSIM AND FRGRSS 


For Vadic and Hayes, 10 means 2400 bps 
For some, 11 means 2400 bps 


Was 1 (300 baud) 

1200 bps? 

Yes 

2400 bps? (preproduction only?) 

BSIM 

If it wasn*t a 3 or 3S it means the Anchor 
Cannected at 300 but sent RC at wrong speed 
BSIM AND ANCHOR 

Wait 3O seconds for valid response 

Wait 1 millisecond 

Time up? 

No, Keep trying 

Go reset if none of these responses 
Update the voice call 


Counter 


Turn up a line on crt 
Turn dtr off while we reset 


BSIM 


Figure 4-1 (cont.). 8080 source code to wait for ring, answer telephone, and set modem to the caller's data rate. 
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RCDIS1: 


a= ae ae 


CHECK 1: 
CHECK 2: 


3 
CHECKS: 
onfale cae 


; 
SET24: 


5 
FINISH: 


PUSH 


CALL 


FUSH 


Creating Meaningful Documentation 


FSW 
RCSHOW 
H, RCSHOW 
PRINTL 


H, RCSHOW 
PRINTL 
PSW 

H 

B 


BSIM 
B, 400 
KDELAY 
B 

A,B 

Cc 
CHECKS 
MDINST 
CHECK 2 
MDINF 
O7FH 


A, OFFH 


DLF 
SET2400 
A, BF2400 
MSPEED 
FINISH 


DLF 

SET200 
A, BF S00 
MSFEED 
FINISH 


DLF’ 
SET1200 
A, BP1200 
MSFEED 


MDCARCE 
REDOIT 
H 

PATCH 


B,6 
DLF1 
EATALL 
ANSW 


=e 


- 


- 


‘we ce ee ae 8 ae 


_ 


=" as 28 as 
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Save A 


And show results cade (RC) 


Force a LF after a CR 


BSIM AND PRGRSS 
Try for 400 ms 


400 ms is up 
Character ready? 
No, keep waiting 
Yes, fetch it 
And strip parity 
And return 


Set error code 
And return 


1 sec delay 
Set port to 2400 bps 


Set speed indicator 


Set port to 300 baud 


Set speed indicator 


Set port to 1200 bps 
And speed indicator 


Still have carrier? 

No, reset modem 

Feset CALL on the stack 
Patch the jump table 


-6 sec more with 1 sec already used= 1.4 sec 
Wait to enter terminal mode 

Clear input port (takes .4 sec more) and 
Greet the user at his speed 


Figure 4-1 (cont.). 8080 source code to wait for ring, answer telephone, and set modem to the caller's data rate. 
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so automatically, and goes on to check the data rate 
at which the remote terminal is operating. 

The comments made in the program are short 
and to the point, but are not excessively cryptic. (If 
you are not familiar with CP/M, you might find some 
of the labels and symbols somewhat strange. All of 
the IF . . . ENDIF segments are conditional assem- 
bly sequences, depending on values set previously 
to define the particular modem and system software 
being used.) 

The purpose of these comments is to guide the 
programmer through the source listing, rather than 
to totally explain everything. The complete descrip- 
tion and explanation will be in the Technical Refer- 
ence Manual, which we will cover in Track 5. 
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TRACK 5 


THE TECHNICAL REFERENCE 


MANUAL 


The Technical Reference Manual, like the comments 
in the program source code, is written for the pro- 
grammer rather than for the user of a program. In 
fact, the source code listing may be included in the 
Technical Reference Manual, since they both deal 
with the same subject — the program itself. 

The comments in the source code, as we have 
seen, deal with the history and purpose of the pro- 
gram, and with the specific purpose and require- 
ments of each block of program code itself. The 
Technical Reference Manual, on the other hand, 
must provide a detailed description of the operation 
of the program. It will refer to various segments of 
code, and will provide complete details on the math- 
ematical techniques and theories being imple- 
mented. 

Because of its nature and purpose, the Technical 
Reference Manual generally has its beginnings along 
with the beginnings of the program itself. It cannot 
be completed, however, until the program itself has 
been completed and made available for general use. 
Let's take a look at what the Technical Reference 
Manual is and what goes into it. 
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Since the Technical Reference Manual must docu- 
ment the background theory and intent of the 
program as well as its actual operation, it should 
include all of the design criteria. This means that the 
original purpose or problem must be stated, along 
with the intended solution procedure. The final flow 
charts (or other types of logic diagrams) should also 
be included. There is no need to include each ex- 
pansion stage, as long as the complete final program 
logic (and preferably a single overview chart as well) 
is provided. 

In addition, the initial mathematical formulas re- 
quired, along with those formulas as modified for 
computer solution, should be provided and ex- 
plained. In fact, all of the solution elements should 
be stated, along with the problem requirements. 

What this means is that your initial design notes 
and paper solutions, all written before you wrote 
even a single line of program code, form the begin- 
ning of your Technical Reference Manual. All 
of this information should be incorporated into the 
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manual. It should be cleaned up, so that it will be 
presented in a neat and organized fashion, but it 
should not be abbreviated much, nor should any of 
the program design steps be taken for granted. 

Keep in mind that the purpose of the Technical 
Reference Manual is to serve as a reference book for 
the program. Thus, you are writing it primarily for 
yourself, to be read at some future time. When you 
need to work on this program, perhaps to update it 
or to correct a flaw that only showed up after long 
use, it may be six months or a year after you com- 
pleted your work on the program. Thus, you will 
have forgotten some of your actions or logic when 
you designed and coded the program. 

Even worse, if you wrote this program for a com- 
pany, but have since either moved or been pro- 
moted, or even assigned to a different task, some 
other programmer may be given the job of updating 
this program. In this case, the new programmer will 
have no initial idea of what you did or how you did 
it. If your Technical Reference Manual is incomplete 
or missing, you or this other programmer will have 
to spend a substantial amount of time just figuring 
out the present program, before any move can be 
made to determine where a correction is required, 
or what correction to make. 


Sector 2: The Coded Program 


You need not include your actual coding process in 
the Technical Reference Manual. You need not even 
include the actual source code listing, although 
many programmers do so, and it is often a very 
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good idea. At the very least you should include 
references to the source code and detailed descrip- 
tions of each logical block of code. 

If you have used a language and compiler that 
converts high-level source code to assembly lan- 
guage (sometimes done with C), you should include 
references to both source codes. With such com- 
pilers, it is a common practice to make corrections 
as necessary to the high-level source code, and then 
to optimize the assembly-language source code for 
minimum memory usage and execution time. In 
such a case, all of the work done on both versions of 
the code should be described and referenced. Later 
updates may require work on both source codes or 
only on the assembly-language code. 

Another procedure sometimes used is to compile 
a program and then to patch the compiled machine 
code to deliberately eliminate unnecessary code. 
This procedure requires some experience with ma- 
chine-language programming, but can be used 
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(with care!) to eliminate code that the compiler in- 
serts because it might be needed in some cases, but 
which is not needed in a particular case. If this sort of 
work is done, it should be carefully and completely 
described in the Technical Reference Manual. 


Sector 3: The Program History 


As we mentioned in Track 4, a brief history of the 
program belongs in the source code listing. This 
consists of a very brief statement of the problem 
noted, along with the statement that the problem 
was fixed. The Technical Reference Manual requires 
additional details of both the problem and its solu- 
tion. 

Any time a problem or bug is found in an existing 
program, the nature of the problem should be de- 
fined and recorded. Then the cause of the problem 
should be identified and the appropriate corrections 
made to the code. This is, in fact, the same proce- 
dure that you followed during the initial debugging 
process. The only difference is that you didn’t catch 
this bug at that time, and it surfaced after the pro- 
gram was in use for a while. 
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When the bug has been located and identified 
and the program has been corrected to eliminate the 
bug, all of this information should be added to the 
Technical Reference Manual, along with the date on 
which the corrected program was released to serv- 
ice. This is very important, because sometimes a 
correction for one bug can introduce another bug, 
which may not be noticed at once. Thus, if a new 
bug does appear after an old bug has been cor- 
rected, a careful check of the modified code is indi- 
cated. If you don’t have the modifications fully 
documented, you can have lots of trouble even 
finding the modified code, let alone modifying it 
again. If you have no record of what you did the first 
time, you might find that you have just changed it 
back to the way it was before, complete with the 
original bug! 

As with the program source code, the complete 
history of all versions of the program should be 
maintained in the Technical Reference Manual. All 
enhancements to the program should be docu- 
mented in detail, along with the problems and cor- 
rections. 

The original history of the program consists of 
nothing more than the date of first release of the 
program for general use. With each modification or 
enhancement to the program, the history of the 
program should be extended to reflect the details of 
the changes. Thus, the Technical Reference Manual 
of an old program that is still in use may have a very 
long historical section. 

As a practical matter, you may wish to keep your 
Technical Reference Manual in a loose-leaf binder 
or notebook. Or, you may wish to use a word pro- 
cessing program and make the changes on disk. 
Either way, there is no need to have a generally 
published copy of the Technical Manual. It is for in- 
house use only. A computer printout or a hand- 
written copy is perfectly satisfactory. 
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Sector 4: Special Program Requirements 
and Characteristics 


We said in Track 2 that the User’s Manual should 
specify any special hardware or minimum memory 
required by the program. Thus, if two floppy drives 
are required, or a hard drive, or even a particular 
interface cartridge must be present, this information 
must be included in the User’s Manual. 

The same information belongs in the Technical 
Reference Manual. In the Technical Manual, the 
reason for the special hardware requirements 
should also be stated. Such explanations may not be 
appropriate in the User’s Manual, but they are 
always appropriate in the Technical Manual. 

For example, a small program can require a 
deceptively large amount of RAM. Such a program 
might be a routine to copy a file from one disk to 
another. A common approach to this is to read as 
much of the source file as possible into memory, 
before sending it to the destination file. This 
minimizes the number of disk accesses and there- 
fore speeds up the process. However, the easiest 
way to accomplish this is to define as much buffer 
space as possible before starting the copy. If you are 
already using the RAM for resident routines, any 
number of problems can result. 

In a case like this, both the Technical Manual and 
the User’s Manual should state that the program 
requires some minimum amount of free RAM. 
However, the Technical Reference Manual should 
go on to state why this restriction exists and how the 
program defines and uses its buffer space. 
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In the same manner, any specific software that is 
required by the program should be specified in the 
User’s Manual and the Technical Manual. Some- 
times this seems obvious, as when your program is 
in fact a “template” or blank worksheet for a spread- 
sheet program or something similar. Other times, 
you may want your program to be able to make use 
of a piece of commercial software. In any case, in 
the User’s Manual you must state the requirements; 
in the Technical Reference Manual you should spec- 
ify in detail exactly what factors or programs are 
required by your program and exactly what sub- 
routines or routines actually get used, and for what 
purposes. 

Unless your program is specifically intended as an 
adjunct to some commercial software, it is a good 
idea to avoid any dependence on other programs. It 
is sometimes convenient to use known functions out 
of such programs during the development stage of 
programming. In any case, you should replace such 
calls with your own code before you release your 
program for general use. Keep in mind that not 
everyone has a given commercial program, so any 
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such requirement limits the usefulness and mar- 
ketability of your program. (It is for exactly this 
reason that our program disks are limited to BASIC 
or machine language for executable programs. 
Other language compilers and assemblers must be 
purchased commercially or in some cases obtained 
from Shareware sources or bulletin boards. We can- 
not be sure that you have any of these, nor can we 
supply them as a general rule. Therefore, we cannot 
use them for our example programs.) 

The Technical Reference Manual must also 
identify any limitations or problems which exist in 
the program. For example, if the program requires 
the DOS wedge to be present, this fact should be 
stated. (The User’s Manual should also state that 
the DOS wedge must be used with the program.) 
Similarly, if your program will not operate with utility 
cartridges such as FastLoad installed, this fact 
should be made clear. 

As any problems or errors are exposed during 
use, the fault and the circumstances under which it 
occurred should be recorded in the Technical Man- 
ual. The list of problems can then be used to help 
determine the improvements and corrections re- 
quired when the program is next updated. 

When the program is actually updated and the 
appropriate corrections made, these problems 
should then be moved to the “history” section of the 
Technical Reference Manual, along with a report of 
the corrections made to solve them. 

The Technical Reference Manual is the most dy- 
namic of the three program documents. It must be 
updated regularly, even between program updates, 
so that all appropriate information will be available 
when the program is corrected or updated. 
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SOLUTIONS AND PROBLEMS 


Now that we have an idea of what documentation is 
all about and why it is so important, it is time to do 
some homework on the subject. First, we will look at 
the problem we posed in the previous module, and 
see a practical solution to it. 


Sector 1: The Character String Display 
Subroutine 


When you entered the character string display 
routine from Module 6, you found that you could not 
even enter the program using FAS or the assembler 
built into the monitor program. This means that one 
or more instructions are somehow illegal. Any such 
instruction will be ignored within the monitor, or will 
produce an error message from FAS. 

Figure 6-1 shows the original subroutine as we 
presented it in Module 6. At first glance, it looks OK. 
It correctly saves the registers that it will use, and 
then makes a duplicate copy that may be modified 
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by the subroutine itself. It then increments the 16-bit 
base address twice to step over the count, and 
resets X to point to the working copy of the required 
data on the stack. 

However, at this point, we find our first problem: 
we cannot enter or use the LDA ($0102,X) in- 
struction. It is refused by the assembler. Obviously 
something is wrong, but what? 

What is wrong here is that indexed indirect 
addressing will only work through the Zero Page, 
while the stack is in Page 1. Thus, we cannot 
indirectly locate characters through stacked infor- 
mation. We must put our pointers in the Zero Page 
in order to access the string this way. 

Accordingly, our first requirement is to store the 
string address somewhere in the Zero Page as well 
as place it on the stack. For the moment, we will use 
locations $F9 and $FA, which are out of the way. 
This means that there will be no interaction between 
the subroutine and the monitor. The first three 
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Figure 6-1. The string display subroutine from Module 6. 


instructions, then, become (prior to the TSX 
instruction): 


PHA 
STA $FA 
TXA 
PHA 
STA  $F9 


If you now type these instructions into the 
computer up to the label LOOP and then test this 
part of the program, you will find that there is 
another problem here. The code that should be 
placing a copy of the count on the stack for use by 
the loop is not doing its job. Rather, it is placing a 
copy of the address of the count on the stack, and 
we already have that. We still want to place the 
count on the stack as a convenient place to put it, 
but we must use indirect addressing through the 
Zero Page to obtain the count itself. 
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Now we could use X as the index register to 
indirectly access the count, but later we will want to 
use it to access the count on the stack. Therefore, 
we will use Y for our Zero Page addressing and X for 
our stack addressing. To do this, we will want to 
save Y on the stack and then load it with 00. The 
next section of code thus becomes: 


TYA 
PHA 
LDY #$00 


Now we can use Y and the string address at 
location $C1 to obtain the string count directly from 
the string in memory. However, since the count will 
be low-byte first, we must hold it while we obtain the 
high byte to be pushed onto the stack first. We can 
readily use X for this purpose: 


LDA ($F9),Y 

TAX 

INC $F9 

BNE INC1 

INC $FA 
INC1: LDA ($F9),Y 

PHA 

TXA 

PHA 

INC $F9 

BNE INC2 

INC $FA 
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This sequence not only reads the count from the 
front of the string, but also steps the pointer past the 
count to the string itself. 

The loop itself must still be preceded by the TSX 
instruction at INC2. In addition, we must adjust the 
base addresses for indexed addressing into the 
stack, because of the fact that the SP (and therefore 
X) will actually point to the first open byte, rather 
than to the last byte pushed onto the stack. The 
resulting code becomes: 


INC2: TSX 

LOOP: LDA ($F9),Y 
JSR CHROUT 
DEC $0101,X 
BNE DEC1 
DEC $0102,X 

DECI: BNE LOOP 
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Testing this code points out a major problem: the 
same character (the first one in the string) gets 
output many times, but the rest of the string is 
ignored. What happened? If we look at the code in 
the loop, we find that the pointer address at $C1 is 
never incremented, so we never obtain a new 
character to output. To correct that, we must insert 
anew 16-bit increment into the loop. The new code, 
starting at LOOP, is: 


LOOP: LDA ($F9),Y 
JSR CHROUT 
INC $F9 
BNE INC3 
INC $FA 
INC3: DEC $0101,X 
BNE DEC1 
DEC $0102,X 
DECI BNE LOOP 


Now we can test the code again, and find that we 
do indeed obtain different characters as output. 
However, further testing, using strings both longer 
and shorter than 256 characters, shows that we do 
not always see the right number of characters. Long 
strings come out 256 characters short. Short strings 
can come out so long as to be uncountable. Clearly, 
the count is not being used correctly. Something is 
still very wrong. 

The problem now is in the decrement portion of 
the loop. The purpose of this code is to decrement 
the count, one character at a time, as characters are 
displayed. As such, it is constructed in the same way 
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as a 16-bit increment. Unfortunately, this isn’t 
working right. Why not? 

The problem is that we are not performing the 
decrement correctly. We are decrementing the 
high-order byte of the count when the low-order 
byte is decremented from 01 to 00, rather than when 
it is being decremented from 00 to FF. Likewise, we 
are testing the decrement of the high byte and 
exiting when it goes from 01 to 00. What we must do 
instead is to test the low byte for 00 before we 
decrement it, and then, if necessary, test and 
decrement the high byte. We must exit the loop 
when both bytes have reached 00, and not before. 
This means that the test and decrement section of 
the loop becomes more complicated. 

Actually, there are several ways to perform a 
16-bit decrement. One of the easiest is to use the 
sequence: 


LDA LOBYTE (A, X, or Y may be used) 

BNE DECLO 

DEC HIBYTE 
DECE@?—BECG=EOBYTE 
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In this case, we must add the 16-bit test for a zero 
count before the DEC HIBYTE instruction. 
Furthermore, we must find a way to force an 
unconditional branch back to LOOP, since the exit 
will be made from the middle of the decrement 
routine, rather than from the end. We could use a 
BNE and BEQ sequence, but it would require a little 
less code if we use a sequence such as SEC and then 
BCS. The resulting complete decrement code looks 
like this: 


LDA $0100,X 
BNE DECLO 
ORA $0101,X 
BEQ EXIT 


DEC $0101,X 
DECLO: DEC $0100,X 
S 


BCS LOOP 
Pets 6 =e 


Of course, the code at EXIT simply cleans up the 
stack, restores the registers, and then returns to the 
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calling program. The complete routine, with all 
corrections installed, is: 


PHA 
STA $FA 
TXA 
PHA 
STA $F9 
TYA 
PHA 
jbbye #$00 
LDA ($F9),Y 
TAX 
INC $F9 
BNE INC1 
INC $FA 
INCL1: LDA ($F9),Y 
PHA 
TXA 
PHA 
INC $F9 
BNE INC2 
INC $FA 
INC2: TSX 
LOOP: LDA ($F9),Y 
JSR CHROUT 
INC $F9 
BNE INC3 
INC $FA 
INC3: LDA $0101,X 


DEC $0102,X 
DECLO: DEC $0101,X 


BCS LOOP 
EXIT: PLA 
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A working copy of this subroutine is included on 
your Program Disk for this module, under the name 
DISPLAY-STRING. It loads at address $3000, and 
occupies the space through $3045. To demonstrate 
it, load it in and then create a character string. We 
used the string: 


2B 00 This is a test of the string output routine. 


The first two hex numbers are the character 
count for the string itself. We placed this sequence 
at location $4000, and then used the R display to 
place $40 in A and $00 in X. To demonstrate the 
routine directly, use the B command of the monitor 
to place a breakpoint at $3045. Then, use G to begin 
execution at $3000. 

If you noticed and questioned the LDA ($0102,X) 
instruction in the original program, congratula- 
tions!! This means that you have become at least 
somewhat familiar with the 6502 instruction set, and 
realized that this instruction was not legal. 

If you questioned the 16-bit decrement procedure 
used, this is also very good. You are recognizing 
what these instructions do, and relating them to real 
operations in the real world. Both of these obser- 
vations are very important to anyone who deals, 
even a little bit, with programming. 

If you discovered on your own the need to adjust 
the base addresses for accessing data on the stack, 
this is excellent. You are developing a real “feel” for 
the operation of the 6502 microprocessor. Since this 
is the heart of the entire Commodore computer, 
your understanding of computer operation and 
programming has improved substantially. 


If you did not notice these points until they were 
pointed out, don’t worry! As in most fields of 
endeavor, practice makes perfect. As you work with 
routines and programs, you will rapidly become 
more proficient with both the language and debug- 
ging operations. If you are truly interested in 
working with programs on this level, you will find the 
procedures becoming clear and automatic. 


Sector 2: A Problem for Next Time. 


In this module, we have described three different 
types of documentation that are required before a 
program can properly be considered to be com- 
plete. However, we have provided examples of only 
two of these: the User’s Manual and the program 
source code. We have not provided any examples of 
the Technical Reference Manual. 

The Technical Reference Manual is the manual 
you are least likely to see ina commercially available 
program. This is because the buyer of a commercial 
program is expected to use the program as is, 
without making any changes or adjustments other 
than any configuration capabilities that are already 
built into the program. If the program does not 
perfectly match the buyer’s requirements, that’s too 
bad — the buyer is not likely to get any help in 
modifying the program. 

As a result, the Technical Reference Manual, 
more than any other, is a roll-your-own kind of thing. 
We have described the kinds of information that it 
should contain, but its organization depends en- 
tirely on the preferences of the original programmer. 
To define a structure in advance would be to place 
limitations on it, rather than to help implement it. 

Now, to gain some experience with such a 
document, your problem for the next module is to 
develop a flowchart to describe the operation of the 
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DISPLAY-STRING subroutine. This will constitute 
a sort of “reverse design” procedure, because you 
will be producing the flowchart from the finished 
routine rather than the other way around. However, 
while this is not the correct design procedure, it is a 
major step toward a clear understanding of an 
existing routine. Such understanding is necessary 
before an existing program can be analyzed or 
modified. Thus, you will be developing the means 
not only for producing a Technical Reference 
Manual, but also for designing your own modifica- 
tions to someone else’s existing program. 

Once you have a complete flowchart for the 
routine, recheck it to make sure that you have 
correctly correlated the functions of the various 
sections, so that the sense of the chart is correct, 
and correctly indicates what is happening at each 
stage of execution of the subroutine. 

When you have completed the flowchart, add 
comments to the assembly-language subroutine to 
help complete its documentation. 

In your next module, we will see how flowcharts 
or similar diagrams may be generated from existing 
programs, as well as how they may then be used as 
a starting point for modifying such programs. Then 
you will be able to examine programs you already 
have, and “patch” them, if necessary, to meet your 
own specific requirements. 
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